NeXT Enterprise Objects Framework 1.1/NeXT Enterprise Objects Framework 1.1.iso/NextDeveloper/Headers/eoaccess/EOFault.h

Text File | 1995-02-10 | 5.3 KB | 145 lines

// EOFault.h
// Copyright (c) 1994, NeXT Computer, Inc.  All rights reserved.

#import <foundation/NSArray.h>
#import <foundation/NSData.h>
#import <foundation/NSDictionary.h>
#import <foundation/NSObject.h>
#import <foundation/NSString.h>

@class EORelationship;
@class EODatabaseChannel;
@class EOQualifier;
@class EOEntity;


// An EOFault represents an Enterprise Object (or an array of Enterprise
// Objects) that hasn't yet been fetched from the database.  When an object
// that has relationships is fetched, EOFaults are created for the
// destinations of those relationships (unless the corresponding objects have
// already been fetched and uniqued).
//
// You can create a fault for a single object--called an "object fault"--or
// for many objects described by a particular qualifier--called an "array
// fault." To-one relationships result in object faults, while to-many
// relationships result in array faults.  An object fault loads the real
// object whenever you message it (with some exceptions; see MESSAGES THAT
// DON'T CAUSE FETCHING below).  An array fault loads its objects as soon as
// you send it any message that requires accessing the contents of the array
// (-objectAtIndex:, -count, and so on).  Objects of either type are called
// "fault objects".
//
// You can use fault objects to defer a fetch--that is, set up for a fetch
// while your channel is in the middle of another operation.  For example,
// your Enterprise Object may need to fetch objects in its
// -takeValuesFromDictionary: method, but since -takeValuesFromDictionary: can
// be invoked during a fetch, it has to defer its own fetch.
//
// Your Enterprise Object may also want to change the manner in which an array
// fault fetches its objects.  If your Enterprise Object has an array fault
// as one of its values, it can change its array fault's fetch order or
// channel in its -awakeForDatabaseChannel: method.  (You can do this in
// -takeValuesFromDictionary: too, but it's best to leave that method as
// general as possible).
//
// MESSAGES THAT DON'T CAUSE FETCHING
//
// A fault object responds to the messages below as if it were the target
// object without causing a fetch to happen.  For example, -class returns the
// class of object that will be fetched, not EOFault.
//
// -dealloc
// -retain
// -retainCount
// -release
// -autorelease
// -zone
// -class
// -isKindOfClass:
// -isMemberOfClass:
// -conformsToProtocol:
// -respondsToSelector:
// -isProxy
// -description
// -printForDebugger:


@interface EOFault
{
    Class isa;
}

+ initialize;
+ (Class)class;
+ self;
+ retain;
+ (void)release;
+ autorelease;
+ (unsigned)retainCount;
+ (BOOL)respondsToSelector:(SEL)sel;
+ (void)doesNotRecognizeSelector:(SEL)sel;
+ forward:(SEL)sel :(marg_list)args;
    // Basic class methods that every object needs to have.

+ objectFaultWithPrimaryKey:(NSDictionary *)key
    entity:(EOEntity *)entity
    databaseChannel:(EODatabaseChannel *)channel
    zone:(NSZone *)zone;
    // Returns an EOFault for the object with the specified primary key and
    // entity. NOTE: this method retains the key rather than copies it.
    // Consequently, the key arguement should not be modified after it is
    // passed as an arguement to this method.

+ (NSArray *)arrayFaultWithQualifier:(EOQualifier *)qualifier
    fetchOrder:(NSArray *)fetchOrder
    databaseChannel:(EODatabaseChannel *)channel
    zone:(NSZone *)zone;
    // Returns an NSArray which will select and fetch its objects
    // according to qualifier and fetchOrder when it is accessed for the
    // first time.

+ (BOOL)isFault:object;
    // Returns YES if object is a fault object, NO otherwise.  You should use
    // this method if you need to know whether an object is in fact a fault
    // object.

+ (void)clearFault:fault;
    // Turns fault into a freshly initialized instance of the target class.
    // Does NOT fetch data for the new instance. This will raise if
    // invoked with an object that isn't a fault object.  You'll rarely need
    // to use this method.

+ (Class)targetClassForFault:fault;
    // Returns the class that will be instantiated when fault is fetched.

+ (NSDictionary *)primaryKeyForFault:fault;
    // Returns the primary key dictionary for an object fault, and nil for an
    // array fault.

+ (EOEntity *)entityForFault:fault;
    // Returns the entity that fault was created with, or as determined by
    // the qualifier for an array fault.  Returns nil if fault isn't a fault
    // object.

+ (EOQualifier *)qualifierForFault:fault;
    // Returns the qualifier used to fetch the object(s) that fault was
    // created for.  Returns nil if fault isn't a fault object.

+ (NSArray *)fetchOrderForFault:fault;
    // Returns the fetch order that fault was created with, or nil if
    // fault isn't an array fault.

+ (EODatabaseChannel *)databaseChannelForFault:fault;
    // Returns the EODatabaseChannel that fault was created with.
    // Returns nil if fault isn't a fault object.

@end


@interface NSObject(EOUnableToFaultToOne)
- (void)unableToFaultWithPrimaryKey:(NSDictionary *)key entity:(EOEntity *)entity databaseChannel:(EODatabaseChannel *)channel;
    // Called when a fetch of a to-one fault does not return exactly one record.
    // The default implementation raises an error.  Clients may override this
    // method to properly initialize the object (or raise).
@end